/**
 * 中文Promise封装 (zh-promise.js)
 * 支持Promise异步操作、链式调用、常用工具方法
 * 中文方法命名 + JSDoc 参数提示
 */

class 异步 {
  /**
   * 构造函数 - 创建异步操作实例
   * @param {Promise|Function|*} 异步处理 Promise对象、executor函数或任意值
   */
  constructor(异步处理) {
    if (异步处理 instanceof Promise) {
      this._值 = 异步处理;
    } else if (typeof 异步处理 === 'function') {
      this._值 = new Promise(异步处理);
    } else {
      this._值 = Promise.resolve(异步处理);
    }
  }

  /**
   * 获取原始Promise对象
   * @returns {Promise} 原始Promise实例
   */
  取值() {
    return this._值;
  }

  /**
   * 获取内部Promise（可用于await）
   * @returns {Promise} 内部Promise实例
   */
  等待() {
    return this._值;
  }

  /**
   * 添加成功回调处理
   * @param {Function} 回调 成功处理函数
   * @returns {异步} 返回this以支持链式调用
   */
  成功(回调) {
    this._值 = this._值.then(回调);
    return this;
  }

  /**
   * 添加失败回调处理
   * @param {Function} 回调 错误处理函数
   * @returns {异步} 返回this以支持链式调用
   */
  失败(回调) {
    this._值 = this._值.catch(回调);
    return this;
  }

  /**
   * 添加最终回调处理（无论成功失败都会执行）
   * @param {Function} 回调 最终处理函数
   * @returns {异步} 返回this以支持链式调用
   */
  总是(回调) {
    this._值 = this._值.finally(回调);
    return this;
  }

  /**
   * 创建指定延迟的异步操作
   * @param {number} 毫秒 延迟时间（毫秒）
   * @returns {异步} 新的异步实例
   */
  延迟(毫秒) {
    return new 异步(resolve => {
      setTimeout(() => {
        resolve();
      }, 毫秒);
    });
  }

  /**
   * 映射Promise的结果值到新值
   * @param {Function} 回调 映射函数，接收当前值并返回新值
   * @returns {异步} 返回this以支持链式调用
   */
  映射(回调) {
    this._值 = this._值.then(回调);
    return this;
  }

  /**
   * 捕获前序操作中的错误并返回新的异步状态
   * @param {Function} 回调 错误处理函数，接收错误并返回恢复值
   * @returns {异步} 新的异步实例
   */
  捕获错误(回调) {
    return new 异步(this._值.catch(回调));
  }

  /** 静态方法 */

  /**
   * 静态方法：创建已成功完成的异步操作
   * @static
   * @param {*} [值=undefined] 成功返回的值
   * @returns {异步} 已成功完成状态的异步实例
   */
  static 成功(值) {
    return new 异步(Promise.resolve(值));
  }

  /**
   * 静态方法：创建已失败的异步操作
   * @static
   * @param {Error|*} 错误 失败的原因
   * @returns {异步} 已失败状态的异步实例
   */
  static 失败(错误) {
    return new 异步(Promise.reject(错误));
  }

  /**
   * 静态方法：并行执行多个异步操作，全部成功才成功
   * @static
   * @param {Array<Promise|异步>} 异步列表 异步操作列表
   * @returns {异步} 包含所有操作结果数组的新异步实例
   */
  static 并行(异步列表) {
    const promises = 异步列表.map(p => p instanceof 异步 ? p._值 : p);
    return new 异步(Promise.all(promises));
  }

  /**
   * 静态方法：并行执行多个异步操作，任一完成即返回
   * @static
   * @param {Array<Promise|异步>} 异步列表 异步操作列表
   * @returns {异步} 包含首个完成结果的新异步实例
   */
  static 任一(异步列表) {
    const promises = 异步列表.map(p => p instanceof 异步 ? p._值 : p);
    return new 异步(Promise.race(promises));
  }

  /**
   * 静态方法：并行执行所有异步操作，返回所有结果状态
   * @static
   * @param {Array<Promise|异步>} 异步列表 异步操作列表
   * @returns {异步} 包含所有操作结果状态数组的新异步实例
   */
  static 所有(异步列表) {
    const promises = 异步列表.map(p => p instanceof 异步 ? p._值 : p);
    return new 异步(Promise.allSettled(promises));
  }

  /**
   * 静态方法：串行执行异步函数列表
   * @static
   * @param {Array<Function>} 异步函数列表 异步函数数组，每个函数返回Promise或值
   * @param {*} [初始值=undefined] 初始值
   * @returns {异步} 包含最终执行结果的新异步实例
   */
  static 串行(异步函数列表, 初始值) {
    return new 异步(
      异步函数列表.reduce(
        (prev, 异步函数) => prev.then(异步函数),
        Promise.resolve(初始值)
      )
    );
  }

  /**
   * 静态方法：创建延迟执行的异步操作
   * @static
   * @param {number} 毫秒 延迟时间（毫秒）
   * @param {*} [值=undefined] 延迟后返回的值
   * @returns {异步} 延迟指定时间后完成的异步实例
   */
  static 延迟(毫秒, 值) {
    return new 异步(resolve => {
      setTimeout(() => resolve(值), 毫秒);
    });
  }

  /**
   * 静态方法：自动重试异步操作直到成功或达到最大次数
   * @static
   * @param {Function} 异步函数 可能失败需要重试的异步函数，应返回Promise
   * @param {number} 最大次数 最大重试次数
   * @param {number} [间隔毫秒=1000] 重试间隔时间（毫秒）
   * @returns {异步} 重试操作的异步实例
   */
  static 重试(异步函数, 最大次数, 间隔毫秒 = 1000) {
    return new 异步((resolve, reject) => {
      let 重试次数 = 0;
      
      const 执行 = () => {
        Promise.resolve()
          .then(异步函数)
          .then(resolve)
          .catch(错误 => {
            重试次数++;
            if (重试次数 >= 最大次数) {
              reject(错误);
            } else {
              setTimeout(执行, 间隔毫秒);
            }
          });
      };
      
      执行();
    });
  }

  /**
   * 静态方法：为异步操作添加超时控制
   * @static
   * @param {Promise|Function|*} 异步操作 要执行的异步操作
   * @param {number} 超时毫秒 超时时间（毫秒）
   * @param {Error} [超时错误=new Error('操作超时')] 超时时抛出的错误
   * @returns {异步} 带超时控制的异步实例，超时后自动失败
   */
  static 超时(异步操作, 超时毫秒, 超时错误 = new Error('操作超时')) {
    return new 异步((resolve, reject) => {
      const 定时器 = setTimeout(() => reject(超时错误), 超时毫秒);
      
      Promise.resolve(异步操作)
        .then(value => {
          clearTimeout(定时器);
          resolve(value);
        })
        .catch(错误 => {
          clearTimeout(定时器);
          reject(错误);
        });
    });
  }

  /**
   * 静态方法：将同步函数包装为异步操作
   * @static
   * @param {Function} 同步函数 要包装的同步函数
   * @returns {异步} 异步包装后的实例，立即完成并返回同步函数的结果
   */
  static 包装(同步函数) {
    return new 异步(resolve => {
      resolve(同步函数());
    });
  }
}

// 规范导出
// 同时支持 ES 模块和 CommonJS 导出
try {
  // 浏览器环境导出
  if (typeof exports === 'undefined') {
    window.异步 = 异步;
  }
} catch (e) {}

// CommonJS 导出

  module.exports = {
    异步,
    default: 异步
  };
  module.exports.异步 = 异步;


// ES 模块导出
// export { 异步 };
// export default 异步;